4.2 Preparing Software for Reuse and Release（整理版）
原始笔记: 4.2 Preparing Software for Reuse and Release.md 原始教程: 4.2 Preparing Software for Reuse and Release created: 2026-07-30 10:30 整理说明: 本版本只整理原笔记已有的软件复用层级、README、CI badge、license、Git tag 与 Semantic Versioning；保留命令及关键参数解释，并对已发布 tag 的修改补充安全边界。
内容简要概括
可复用软件不仅要能重复产生结果，还要让其他人能够理解、安装、使用和修改。README、CI 状态、license 和清晰的发布 tag 共同提供使用入口、质量信号、法律边界与稳定版本标识；Semantic Versioning 则用版本号表达兼容性变化。
软件复用、README、CI badge、LICENSE、MIT、Git tag、annotated tag、Semantic Versioning、MAJOR.MINOR.PATCH、软件发布、可复现性、版本管理
目录
- 1. 软件复用的五个层级
- 2. README 的最低结构
- 3. 在 README 中展示 CI Badge
- 4. 添加软件许可证
- 5. 使用 Git Tag 标记发布
- 6. Semantic Versioning
- 7. 已发布 Tag 的安全边界
1. 软件复用的五个层级
软件的可复用程度可以按以下层级理解：
- 可重新运行（Re-runnable）：代码能够再次执行，但不保证结果一致；
- 可重复（Repeatable）：多次运行能够得到相同结果；
- 可复现（Reproducible）：使用相同软件版本和输入数据，可以重新生成已发布的研究结果；
- 可复用（Reusable）：软件容易使用、理解和修改；
- 可复制实现（Replicable）：其他人能够根据论文描述重新实现算法，并用原始实现消除描述中的歧义。
后一个层级通常以前面的层级为基础。研究软件至少应以 Reusable 为目标：
- Reproducible 关注能否重新得到相同研究结果；
- Reusable 进一步关注其他人能否理解、运行、修改和扩展软件。
2. README 的最低结构
README 是新用户理解项目的第一入口。它至少应回答：
- 项目解决什么问题；
- 软件有哪些主要功能；
- 运行前需要哪些依赖；
- 如何安装和执行；
- 如何贡献和获取帮助；
- 如何引用以及使用什么许可证。
2.1 可复用 README 模板
# 项目名称
一句话描述项目解决什么问题。
## Main Features
- 主要功能 1
- 主要功能 2
## Prerequisites
- 运行时依赖
- 测试或开发依赖
## Installation
安装步骤。
## Usage
最基本的使用示例。
## Contributing
如何提交 Issue、代码和 Pull Request。
## Getting Help
问题反馈和获取帮助的渠道。
## Credits
贡献者和致谢。
## Citation
学术引用方式。
## License
许可证说明。
README 中的示例应尽量短小、可复制，并与当前发布版本一致。依赖列表需要区分普通用户运行软件所需的依赖，以及只在测试和开发时使用的可选依赖。
3. 在 README 中展示 CI Badge
GitHub Actions 可以为 workflow 提供 SVG 状态徽章，用于显示目标分支最近一次 CI 是否成功。
Markdown 图片语法是：
- 方括号中的文字是图片无法加载时显示的替代文本；
- 圆括号中的 URL 是 GitHub 动态生成的 SVG 图片地址。
3.1 Badge URL 的组成
https://github.com/<your_github_username>/
python-intermediate-inflammation/
actions/workflows/main.yml/
badge.svg?branch=main
| 部分 | 含义 |
|---|---|
<your_github_username> |
GitHub 用户名或组织名 |
python-intermediate-inflammation |
仓库名称 |
actions/workflows/main.yml |
workflow 配置文件 |
badge.svg |
请求 SVG 状态徽章 |
branch=main |
展示 main 分支的 workflow 状态 |
Badge 是当前 CI 状态的快速信号，但不能代替 README 中的测试说明或发布验证记录。
4. 添加软件许可证
许可证明确其他人可以如何使用、修改和分发软件。没有许可证并不等于允许自由使用，因此准备复用和发布时应明确选择并提交许可证。
4.1 获取 MIT License 模板
安装 GitHub CLI 后，可以通过 GitHub API 获取 MIT 模板：
gh api licenses/mit --jq .body > LICENSE
gh api licenses/mit：请求 GitHub 的 MIT license API；--jq .body：只提取响应中的正文；> LICENSE：把正文写入仓库根目录的LICENSE文件。
打开 LICENSE，将：
Copyright (c) [year] [fullname]
替换为真实年份和权利人：
Copyright (c) 2026 Your Name
4.2 提交许可证
git add LICENSE
git commit -m "docs: add MIT license"
git push
README 中应同时说明：
## License
This project is licensed under the MIT License.
See [LICENSE](LICENSE) for details.
4.3 在 pyproject.toml 中声明
现代 Python 项目可以在 pyproject.toml 中记录 license：
[project]
license = "MIT"
license-files = ["LICENSE"]
MIT是 SPDX identifier；license-files确保构建的发布包包含许可证文件。
5. 使用 Git Tag 标记发布
Git tag 是指向特定 commit 的人类可读名称：
v1.0.0 → commit 2df4bf...
分支会随着新提交移动，而发布 tag 通常应保持不变：
main：A → B → C → D
↑
v1.0.0
这里 main 可以继续前进到 D，但 v1.0.0 仍然指向 C。
5.1 查看本地 Tag
git tag
该命令列出本地仓库中的所有 tag。
5.2 创建 Annotated Tag
git tag -a v1.0.0 -m "Version 1.0.0"
-a：创建 annotated tag；v1.0.0：tag 名称；-m：写入 tag 说明；- 未指定 commit 时，默认标记当前
HEAD。
Annotated tag 会保存创建者、创建时间、说明和目标 commit，适合正式发布。
5.3 查看 Tag 内容
git show v1.0.0
输出通常包括：
- tag 名称、Tagger、时间和说明；
- tag 指向的 commit；
- 该 commit 的提交信息和 diff。
5.4 推送 Tag
普通分支推送不会自动发布本地 tag：
git push origin main
单独推送准备发布的 tag：
git push origin v1.0.0
也可以推送所有本地 tag：
git push origin --tags
实际项目中优先推送指定 tag，避免把实验或临时 tag 一并上传。
6. Semantic Versioning
Semantic Versioning 使用：
例如：
1.4.2
| 位置 | 何时增加 | 示例 |
|---|---|---|
MAJOR |
产生不兼容的 API 修改 | 1.2.3 → 2.0.0 |
MINOR |
向后兼容地增加功能 | 1.2.3 → 1.3.0 |
PATCH |
向后兼容地修复问题 | 1.2.3 → 1.2.4 |
预发布版本可以写成：
1.0.0-alpha.1
1.0.0-beta.1
1.0.0-rc.1
其中 rc 表示 release candidate。
版本号变化向用户传达更新风险：版本号不应只作为装饰，每次重新发布都应使用新的版本。
7. 已发布 Tag 的安全边界
本地、尚未推送的 tag 可以重新指向目标 commit：
git tag -f v1.0.0 main
-f 会覆盖本地同名 tag，因此执行前应先用 git show v1.0.0 检查旧目标。
对已发布版本，推荐修复后创建新版本，例如：
git tag -a v1.0.1 -m "Version 1.0.1"
git push origin v1.0.1
只有在明确确认无人依赖旧 tag、团队已经协调并核对远程目标时，才考虑更正错误 tag；这应作为受控的仓库维护操作，而不是常规发布流程。